home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1994 September / macformat-004.iso / Shareware City / Utilities / gdbm-1.7.3 / doc / gdbm.3 next >
Encoding:
Text File  |  1994-05-21  |  12.7 KB  |  540 lines  |  [TEXT/ttxt]
  1. .ds ve 1.7.3
  2. .TH GDBM 3 5/19/94
  3. .SH NAME
  4. GDBM - The GNU database manager.  Includes \fBdbm\fR and \fBndbm\fR
  5. compatability. (Version \*(ve.)
  6. .SH SYNOPSIS
  7. .B #include <gdbm.h>
  8. .PP
  9. .SM
  10. .B extern gdbm_error
  11. .br
  12. .B gdbm_errno
  13. .PP
  14. .B extern char
  15. .br
  16. .B *gdbm_version
  17. .PP
  18. .B GDBM_FILE
  19. .br
  20. .B gdbm_open (name, block_size, read_write, mode, fatal_func)
  21. .br
  22. .B char * name;
  23. .br
  24. .B int block_size, read_write, mode;
  25. .br
  26. .B void (*fatal_func) ();
  27. .PP
  28. .B void
  29. .br
  30. .B gdbm_close (dbf)
  31. .br
  32. .B GDBM_FILE dbf;
  33. .PP
  34. .B int
  35. .br
  36. .B gdbm_store (dbf, key, content, flag)
  37. .br
  38. .B GDBM_FILE dbf;
  39. .br
  40. .B datum key, content;
  41. .br
  42. .B int flag;
  43. .PP
  44. .B datum
  45. .br
  46. .B gdbm_fetch (dbf, key)
  47. .br
  48. .B GDBM_FILE dbf;
  49. .br
  50. .B datum key;
  51. .PP
  52. .B int
  53. .br
  54. .B gdbm_delete (dbf, key)
  55. .br
  56. .B GDBM_FILE dbf;
  57. .br
  58. .B datum key;
  59. .PP
  60. .B datum
  61. .br
  62. .B gdbm_firstkey (dbf)
  63. .br
  64. .B GDBM_FILE dbf;
  65. .PP
  66. .B datum
  67. .br
  68. .B gdbm_nextkey (dbf, key)
  69. .br
  70. .B GDBM_FILE dbf;
  71. .br
  72. .B datum key;
  73. .PP
  74. .B int
  75. .br
  76. .B gdbm_reorganize (dbf)
  77. .br
  78. .B GDBM_FILE dbf;
  79. .PP
  80. .B void
  81. .br
  82. .B gdbm_sync (dbf)
  83. .br
  84. .B GDBM_FILE dbf;
  85. .PP
  86. .B int
  87. .br
  88. .B gdbm_exists (dbf, key)
  89. .br
  90. .B GDBM_FILE dbf;
  91. .br
  92. .B datum key;
  93. .PP
  94. .B char *
  95. .br
  96. .B gdbm_strerror (errno)
  97. .br
  98. .B gdbm_error errno;
  99. .PP
  100. .B int
  101. .br
  102. .B gdbm_setopt (dbf, option, value, size)
  103. .br
  104. .B GDBM_FILE dbf;
  105. .br
  106. .B int option;
  107. .br
  108. .B int *value;
  109. .br
  110. .B int size;
  111. .PP
  112. .PP
  113. .B DBM Compatability routines:
  114. .PP
  115. .B #include <dbm.h>
  116. .PP
  117. .SM
  118. .B int
  119. .br
  120. .B dbminit (name)
  121. .br
  122. .B char *name;
  123. .PP
  124. .B int
  125. .br
  126. .B store (key, content)
  127. .br
  128. .B datum key, content;
  129. .PP
  130. .B datum
  131. .br
  132. .B fetch (key)
  133. .br
  134. .B datum key;
  135. .PP
  136. .B int
  137. .br
  138. .B delete (key)
  139. .br
  140. .B datum key;
  141. .PP
  142. .B datum
  143. .br
  144. .B firstkey ()
  145. .PP
  146. .B datum
  147. .br
  148. .B nextkey (key)
  149. .br
  150. .B datum key;
  151. .PP
  152. .B int
  153. .br
  154. .B dbmclose ()
  155. .PP
  156. .PP
  157. .B NDBM Compatability routines:
  158. .PP
  159. .B #include <ndbm.h>
  160. .PP
  161. .SM
  162. .B DBM
  163. .br
  164. .B *dbm_open (name, flags, mode)
  165. .br
  166. .B char *name;
  167. .br
  168. .B int flags, mode;
  169. .PP
  170. .B void
  171. .br
  172. .B dbm_close (file)
  173. .br
  174. .B DBM *file;
  175. .PP
  176. .B datum
  177. .br
  178. .B dbm_fetch (file, key)
  179. .br
  180. .B DBM *file;
  181. .br
  182. .B datum key;
  183. .PP
  184. .B int
  185. .br
  186. .B dbm_store (file, key, content, flags)
  187. .br
  188. .B DBM *file;
  189. .br
  190. .B datum key, content;
  191. .br
  192. .B int flags;
  193. .PP
  194. .B int
  195. .br
  196. .B dbm_delete (file, key)
  197. .br
  198. .B DBM *file;
  199. .br
  200. .B datum key;
  201. .PP
  202. .B datum
  203. .br
  204. .B dbm_firstkey (file)
  205. .br
  206. .B DBM *file;
  207. .PP
  208. .B datum
  209. .br
  210. .B dbm_nextkey (file)
  211. .br
  212. .B DBM *file;
  213. .PP
  214. .B int
  215. .br
  216. .B dbm_error (file)
  217. .br
  218. .B DBM *file;
  219. .PP
  220. .B int
  221. .br
  222. .B dbm_clearerr (file)
  223. .br
  224. .B DBM *file;
  225. .PP
  226. .B int
  227. .br
  228. .B dbm_pagfno (file)
  229. .br
  230. .B DBM *file;
  231. .PP
  232. .B int
  233. .br
  234. .B dbm_dirfno (file)
  235. .br
  236. .B DBM *file;
  237. .PP
  238. .B int
  239. .br
  240. .B dbm_rdonly (file)
  241. .br
  242. .B DBM *file;
  243.  
  244.  
  245. .SH DESCRIPTION
  246. GNU dbm is a library of routines that manages data files that contain
  247. key/data pairs.  The access provided is that of storing, 
  248. retrieval, and deletion by key and a non-sorted traversal of all
  249. keys.  A process is allowed to use multiple data files at the
  250. same time.
  251.  
  252. A process that opens a gdbm file is designated as a "reader" or a
  253. "writer".  Only one writer may open a gdbm file and many readers may
  254. open the file.  Readers and writers can not open the gdbm file at the
  255. same time. The procedure for opening a gdbm file is:
  256.  
  257.   GDBM_FILE dbf;
  258.  
  259.   dbf = gdbm_open ( name, block_size, read_write, mode, fatal_func )
  260.  
  261. \fIName\fR is the name of the file (the complete name,
  262. gdbm does not append any characters to this name).  \fIBlock_size\fR is
  263. the size of a single transfer from disk to memory. This parameter is
  264. ignored unless the file is a new file.  The minimum size is 512.  If
  265. it is less than 512, dbm will use the stat block size for the file system.
  266. \fIRead_write\fR can have one of the following values:
  267. .br
  268. .B GDBM_READER
  269. reader
  270. .br
  271. .B GDBM_WRITER
  272. writer
  273. .br
  274. .B GDBM_WRCREAT
  275. writer - if database does not exist create new one
  276. .br
  277. .B GDBM_NEWDB
  278. writer - create new database regardless if one exists
  279. .br
  280. For the last three (writers of the database) there is an extra value that
  281. that can be added to \fIread_write\fR by bitwise or,
  282. .B GDBM_FAST.
  283. This requests that gdbm write the database with no disk file syncronization.
  284. This allows faster writes, but may produce an inconsistant database in
  285. the event of abnormal termination of the writer.
  286. .br
  287. \fIMode\fR is the file mode (see \fBchmod(2)\fR and \fBopen(2)\fR) if the
  288. file is created. \fI(*Fatal_func) ()\fR is a function for dbm to call
  289. if it detects a fatal error. The only parameter of this function is a string.
  290. If the value of 0 is provided, gdbm will use a default function.
  291.  
  292. The return value \fIdbf\fR is the pointer needed by all other routines to
  293. access that gdbm file.  If the return is the NULL pointer, \fBgdbm_open\fR
  294. was not successful.  The errors can be found in \fIgdbm_errno\fR for gdbm
  295. errors and in \fIerrno\fR for system errors.  (For error codes, see
  296. gdbmerrno.h.)
  297.  
  298. In all of the following calls, the parameter \fIdbf\fR refers to the pointer
  299. returned from \fBgdbm_open\fR.
  300.  
  301. It is important that every file opened is also closed.  This is needed to
  302. update the reader/writer count on the file.  This is done by:
  303.  
  304.   gdbm_close (dbf);
  305.  
  306.  
  307. The database is used by 3 primary routines.  The first stores data in the
  308. database.
  309.  
  310.   ret = gdbm_store ( dbf, key, content, flag )
  311.  
  312. \fIDbf\fR is the pointer returned by \fBgdbm_open\fR.  \fIKey\fR is the
  313. key data.  \fIContent\fR is the data to be associated with the \fIkey\fR.
  314. \fIFlag\fR can have one of the following values:
  315. .br
  316. .B GDBM_INSERT
  317. insert only, generate an error if key exists
  318. .br
  319. .B GDBM_REPLACE
  320. replace contents if key exists.
  321.  
  322. If a reader calls \fBgdbm_store, the return value will be  -1.
  323. If called with GDBM_INSERT and \fIkey\fR is in the database, the return
  324. value will be 1.  Otherwise, the return value is 0.
  325.  
  326. \fINOTICE: If you store data for a key that is already in the data base,
  327. gdbm replaces the old data with the new data if called with GDBM_REPLACE.
  328. You do not get two data items for the same key and you do not get an
  329. error from gdbm_store.
  330.  
  331. NOTICE: The size in gdbm is not restricted like dbm or ndbm.  Your data
  332. can be as large as you want.\fR
  333.  
  334.  
  335. To search for some data:
  336.  
  337.   content = gdbm_fetch ( dbf, key )
  338.  
  339. \fIDbf\fR is the pointer returned by \fBgdbm_open\fR.  \fIKey\fR is
  340. the key data.
  341.  
  342.  
  343. If the \fIdptr\fR element of the return value is NULL, no data was
  344. found.  Otherwise the return value is a pointer to the found data.
  345. The storage space for the \fIdptr\fR element is allocated using
  346. \fBmalloc(3C)\fR.  \fBGdbm\fI does not automatically free this data.
  347. It is the programmer's responsibility to free this storage when it is
  348. no longer needed.\fR
  349.  
  350.  
  351. To search for some data, without retrieving it:
  352.  
  353.   ret = gdbm_exists ( dbf, key )
  354.  
  355. \fIDbf\fR is the pointer returned by \fBgdbm_open\fR.  \fIKey\fR is
  356. the key data to search for.
  357.  
  358. If the \fIkey\fR is found within the database, the return value \fIret\fR
  359. will be true.  If nothing appropiate is found, \fIret\fR will be false.
  360. This routine is useful for checking for the existance of a record,
  361. without performing the memory allocation done by \fBgdbm_fetch\fR.
  362.  
  363.  
  364. To remove some data from the database:
  365.  
  366.   ret = gdbm_delete ( dbf, key )
  367.  
  368. \fIDbf\fR is the pointer returned by \fBgdbm_open\fR.  \fIKey\fR is the
  369. key data.
  370.  
  371. The return value is -1 if the item is not present or the requester is a reader.
  372. The return value is 0 if there was a successful delete.
  373.  
  374.  
  375. The next two routines allow for accessing all items in the database.  This 
  376. access is not key sequential, but it is guaranteed to visit every key in
  377. the database once.  (The order has to do with the hash values.)
  378.  
  379.   key = gdbm_firstkey ( dbf )
  380.  
  381.   nextkey = gdbm_nextkey ( dbf, key )
  382.  
  383. \fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the
  384. key data.
  385.  
  386. The return values are both of type \fBdatum\fR.  If the \fIdptr\fR
  387. element of the return value is NULL, there is no first key or next key.
  388. Again notice that \fIdptr\fR points to data allocated by \fBmalloc(3C)\fR
  389. and \fBgdbm\fR will not free it for you. 
  390.  
  391. These functions were intended to visit the database in read-only algorithms,
  392. for instance, to validate the database or similar operations.
  393.  
  394. File `visiting' is based on a `hash table'.  \fIgdbm_delete\fR re-arranges the
  395. hash table to make sure that any collisions in the table do not leave some item
  396. `un-findable'.  The original key order is NOT guaranteed to remain unchanged in
  397. ALL instances.  It is possible that some key will not be visited if a loop like
  398. the following is executed:
  399.  
  400.    key = gdbm_firstkey ( dbf );
  401.    while ( key.dptr ) {
  402.       nextkey = gdbm_nextkey ( dbf, key );
  403.       if ( some condition ) {
  404.          gdbm_delete ( dbf, key );
  405.          free ( key.dptr );
  406.       }
  407.       key = nextkey;
  408.    }
  409.  
  410.  
  411. The following routine should be used very infrequently.
  412.   
  413.   ret = gdbm_reorganize ( dbf )
  414.  
  415. If you have had a lot of deletions and would like to shrink the space
  416. used by the \fBgdbm\fR file, this routine will reorganize the database.
  417. \fBGdbm\fR will not shorten the length of a \fBgdbm\fR file except by
  418. using this reorganization.  (Deleted file space will be reused.)
  419.  
  420.  
  421. If you use the \fBGDBM_FAST\fR value in your \fBgdbm_open\fR call, 
  422. the following routine can be used to guarantee that the database is
  423. physically written to the disk file.
  424.  
  425.   gdbm_sync ( dbf )
  426.  
  427. It will not return until the disk file state is syncronized with the
  428. in-memory state of the database.
  429.  
  430.  
  431. To convert a \fBgdbm\fR error code into English text, use this routine:
  432.  
  433.   ret = gdbm_strerror ( errno )
  434.  
  435. Where \fBerrno\fR is of type \fBgdbm_error\fR, usually the global
  436. variable \fBgdbm_errno\fR.  The appropiate phrase is returned.
  437.  
  438.  
  439. \fBGdbm\fR now supports the ability to set certain options on an
  440. already open database.
  441.  
  442.   ret = gdbm_setopt ( dbf, option, value, size )
  443.  
  444. Where \fBdbf\fR is the return value from a previous call to \fBgdbm_open\fR,
  445. and \fBoption\fR specifies which option to set.  The valid options are
  446. currently:
  447.  
  448.   GDBM_CACHESIZE - Set the size of the internal bucket
  449.   cache. This option may only be set once on each \fBGDBM_FILE\fR
  450.   descriptor, and is set automatically to 100 upon the first
  451.   access to the database.
  452.  
  453.   GDBM_FASTMODE - Set \fBfast mode\fR to either on or off.  This
  454.   allows \fBfast mode\fR to be toggled on an already open and
  455.   active database. \fBvalue\fR (see below) should be set to either
  456.   TRUE or FALSE.
  457.  
  458. \fBvalue\fR is the value to set \fBoption\fR to, specified as an integer
  459. pointer.  \fBsize\fR is the size of the data pointed to by \fBvalue\fR.
  460. The return value will be -1 upon failure, or 0 upon success.  The global
  461. variable \fBgdbm_errno\fR will be set upon failure.
  462.  
  463. For instance, to set a database to use a cache of 10, after opening it
  464. with \fBgdbm_open\fR, but prior to accessing it in any way, the following
  465. code could be used:
  466.  
  467.   int value = 10;
  468.   
  469.   ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int));
  470.  
  471.  
  472. The following two external variables may be useful:
  473.  
  474. \fBgdbm_errno\fR is the variable that contains more information about
  475. gdbm errors.  (gdbm.h has the definitions of the error values and
  476. defines gdbm_errno as an external variable.)
  477. .br
  478. \fBgdbm_version\fR is the string containing the version information.
  479.  
  480.  
  481. There are a few more things of interest.  First, \fBgdbm\fR files are
  482. not "sparse".  You can copy them with the UNIX \fBcp(1)\fR command and
  483. they will not expand in the copying process.  Also, there is a
  484. compatibility mode for use with programs that already use UNIX
  485. \fBdbm\fR.  In this compatibility mode, no \fRgdbm\fR file pointer is
  486. required by the programmer, and only one file may be opened at a time.
  487. All users in compatibility mode are assumed to be writers.  If the
  488. \fBgdbm\fR file is a read only, it will fail as a writer, but will
  489. also try to open it as a reader.  All returned pointers in datum
  490. structures point to data that \fBgdbm\fR WILL free.  They should be
  491. treated as static pointers (as standard UNIX \fBdbm\fR does).
  492.  
  493.  
  494. .SH LINKING
  495. This library is accessed by specifying \fI-lgdbm\fR as the last
  496. parameter to the compile line, e.g.:
  497. .sp
  498.     gcc -o prog prog.c -lgdbm
  499.  
  500.  
  501. .SH BUGS
  502.  
  503. .SH "SEE ALSO"
  504. dbm, ndbm
  505.  
  506. .SH AUTHOR
  507. by Philip A. Nelson.
  508. Copyright (C) 1990  Free Software Foundation, Inc.
  509.  
  510. GDBM is free software; you can redistribute it and/or modify
  511. it under the terms of the GNU General Public License as published by
  512. the Free Software Foundation; either version 1, or (at your option)
  513. any later version.
  514.  
  515. GDBM is distributed in the hope that it will be useful,
  516. but WITHOUT ANY WARRANTY; without even the implied warranty of
  517. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  518. GNU General Public License for more details.
  519.  
  520. You should have received a copy of the GNU General Public License
  521. along with GDBM; see the file COPYING.  If not, write to
  522. the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
  523.  
  524. You may contact the author by:
  525. .br
  526.    e-mail:  phil@wwu.edu
  527. .br
  528.   us-mail:  Philip A. Nelson
  529. .br
  530. Computer Science Department
  531. .br
  532. Western Washington University
  533. .br
  534. Bellingham, WA 98226
  535.  
  536. You may contact the current maintainer by:
  537. .br
  538.    e-mail:  downsj@CSOS.ORST.EDU
  539.  
  540.